Collection of Tools & Utilities/Collection of Tools and Utilities.iso/basic/qbser225.zip/QBSERIAL.DOC

Text File | 1992-07-04 | 33KB | 729 lines

                                 QBserial version 2.25

                  Serial I/O Routines for use with QuickBASIC & BC6/7

          This library will provide you with serial I/O communications
          routines for use in QuickBASIC 4.x (with or without PDQ), and the
          Microsoft Basic Compiler 7.x Professional Development System. No
          longer are you forced to use the poor communications support
          provided by QB.  This program will allow you to control 8250 and
          16450 type communications ports (UARTS) at speeds of up to 115200
          baud. Communication ports 1 - 4, and non-standard addresses are
          supported. You will no longer have problems with the DTR signal.
          DTR is left in the same state it was in when before you called this
          driver, or it can be controlled by your program. The serial driver
          includes XON/XOFF and CTS/RTS handshaking. Serial input is
          interrupt driven, using any IRQ you specify (1 - 15), with incoming
          XOFF flow control (if enabled), or RTS flow control (if enabled) to
          prevent overrunning the input buffer. These are the same serial I/O
          routines used in Sparkware's Qmail door, and the User Database
          System Doors "Query Door" and "Upload Door".

          The driver was written with Microsoft's C, and compiled with
          version 6.0a of that compiler. This driver is useable with
          QuickBASIC version 4.x, and Basic Compiler 6.x & 7.x PDS. (With or
          without PDQ). BC 1.x, QuickBASIC 2.x, and 3.x are not supported by
          this driver. The reason is that versions of QuickBASIC prior to 4.0
          do not support the extensive multi-language interface that QB4.x
          has (via the DECLARE statement and Microsoft language extensions).
          Throughout this manual QB will be used to refer to both QuickBASIC
          and the Basic Compilers (6.x & 7.x PDS).

          Before the driver can be used, the following DECLARE statements
          must be added to the beginning of your QB program:

          DECLARE SUB OpenComm CDECL ALIAS "_open_comm" (BYVAL Port%, BYVAL_
                               IRQ%, BYVAL Wlen%, BYVAL Parity%, BYVAL Baud&,
                               BYVAL HS%)
          DECLARE SUB CloseComm CDECL ALIAS "_close_comm" ()
          DECLARE FUNCTION WriteChar% CDECL (BYVAL Ascii%)
          DECLARE FUNCTION ReadChar% CDECL ()
          DECLARE SUB Transmit CDECL ALIAS "_transmit_string" (addr$)
          DECLARE FUNCTION DataWaiting% CDECL ALIAS "_data_waiting" ()
          DECLARE SUB ClearInputBuffer CDECL ALIAS "_clear_input_buffer" ()
          DECLARE SUB CarrierDetect CDECL ALIAS "_carrier_detect_flag"_
                                    (BYVAL OnOff%)
          DECLARE FUNCTION CarrierLost% CDECL ALIAS "_carrier_state" ()
          DECLARE SUB DTRcontrol CDECL ALIAS "_dtr" (BYVAL OnOff%)
          DECLARE SUB RTScontrol CDECL ALIAS "_rts" (BYVAL OnOff%)
          DECLARE FUNCTION DriverCopyright% CDECL ()



        QBSERIAL User Manual - V 2.25                              Page 1


          These declarations specify all the entry points into the serial
          driver, They are in the include file QBSERIAL.DEC. DO NOT change
          them or the driver may not function.

          Refer to the included sample programs SIMPLE.BAS & PCBDOOR.BAS,
          they use most of the calls described below.



                                  Port Initialization

          OpenComm Port%, IRQ%, Wordlen%, Parity%, Baudrate&, HS%

          Port%     This is an integer value. If the specified port is 1 to
                    4, the driver opens that port. If you specify the port as
                    ZERO (0) the driver enters "LOCAL" mode. This allows you
                    to call the driver with data, but the driver won't send
                    anything. This is useful when working with "doors". if
                    you specify the port as any other value, QBserial will
                    use that as the base address for the port. This allows
                    you to work with non-standard I/O addresses. Note however
                    that if you open a non-standard port, you must specify an
                    IRQ value of 1 to 15

          IRQ%      Specifies which interrupt to use with this port. If the
                    value of IRQ% is ZERO (0), then the default IRQ values
                    are used (COM1 & COM3 use IRQ4, COM2 & COM4 use IRQ3).
                    This is what most applications will use. Specify an IRQ
                    value of 1 through 15 when you want to use an IRQ value
                    other than the default. Such as when you want to use
                    IRQ15 with COM3. NOTE: Be careful when choosing an IRQ
                    value other than the default. Most machines use some of
                    the other IRQ inputs for other machine functions such as
                    the Hard drive and system clock. QBserial DOES NOT chain
                    the interrupt, it takes it over entirely. If you choose
                    an IRQ that is used for something already, your machine
                    will most certainly operate improperly.

          Wordlen%  an integer specifying the word length of the serial data.
                    It has a value of 7 or 8.

          Parity%   an integer, 0 = NONE, 1 = ODD, 2 = EVEN.

          BaudRate& is a LONG INTEGER representing the desired baud rate.
                    Valid numbers are 0, 300, 1200, 2400, 4800, 9600, 19200,
                    38400, 57600, and 115200. The value you send is NOT
                    checked and I assume you could generate crazy baud rates
                    if desired. 115200 is the absolute maximum rate that can
                    be generated. If you specify a baud rate of ZERO then the
                    serial port is used AS-IS. The rate, word length, &
                    parity are NOT changed. This is useful for door operation


        QBSERIAL User Manual - V 2.25                              Page 2


                    since the port is already initialized at the proper
                    settings when you get control.

          HS%       an integer specifying the type of handshake you wish to
                    use between the CPU and Modem (or destination device).
                    Valid numbers are: 0 = NO handshake, 1 = XON/XOFF, 2 =
                    CTS/RTS, 3 = XON/XOFF and CTS/RTS.


                                     Serial Output

          To send a string of data out the serial port, you use the
          "Transmit" call as follows:

               Temp$ = "Transmit this..."
               Transmit Temp$

                    or

               Transmit "Send this also...."

          If you want to transmit single characters, you can use the
          "WriteChar" function. Transmit calls WriteChar to send the actual
          characters to the port. If you wish to use WriteChar, it has the
          following format:

               Status% = WriteChar(Char%)

          Char% is the integer value of the character you want to send, it is
          not a string. Status% is an integer returned by WriteChar, it is
          NON-ZERO if the character was actually sent to the port, and ZERO
          if the character was not sent. WriteChar will loop indefinitely on
          CTS hold, XOFF hold, or Transmit Buffer Busy. These loops will exit
          if carrier is lost in FULL or PARTIAL modes and return a ZERO
          status%. WriteChar gives you more low level control of the sending
          of characters, but you must send each character separately and
          monitor its status.

          The Transmit function monitors the status of its calls to WriteChar
          and triggers QuickBASIC's User Event trap (UEVENT) if a carrier
          loss occurs in FULL mode. The UEVENT trap (FULL mode) is used by